Summary

• Adds docs/contributing.md — everything in docs/ describes the product; nothing described the repository that produces it. Covers clone-to-green setup, the four local gates (and that there is no CI), rebuilding the knowledge bundle, and pointers to CLAUDE.md / CONVENTIONS.md.
• Documents the prerequisite that cost most of a session to find: frontmatter hooks in a project subagent only run once the workspace trust dialog has been accepted for the folder (2.1.218+), and until then they fail silently. /hooks shows nothing for an inactive agent, and hasCompletedProjectOnboarding can read true while trust is still false — so an old checkout looks set up and quietly isn't. Includes a one-liner to check it.
• Other known hiccups: agent definitions are cached per session, snapshot drift after engine changes is expected and how to regenerate, CHANGELOG.md is generated, shipped .sh migrations are frozen. Plus the never-pipe-a-gate rule, which produced a falsely-green report before.
• Linked from both README.md and docs/README.md.

Deliberately thin — it grows as we hit things.

Test plan

• Docs only; no behaviour changes.
• The trust-check one-liner in the page was run against this repo and returns the expected value.

🤖 Generated with Claude Code

Stack

1. docs(design): prose-tests programme design log #544
2. feat(prose-tests): the framework — cases, worlds, runner, skill #545
3. test(prose): feature happy-path corpus — five worlds, seven cases #546
4. test(prose): bugfix corpus — the investigation-centric surfaces #548
5. test: retry recursive teardown removals — kill a class of phantom failures #549
6. fix(entry-skills): close the handoff fences — six files render their arms wrong #550
7. docs: a contributing page for working on the system #551 👈 current
8. fix(entry-skills): every handoff arm says to invoke the skill #552
9. fix(implementation): environment setup belongs to the setup reference alone #553
10. fix(prose-tests): the asserter is told which substitutions were armed #554
11. feat(prose-tests): the mid-flow substitution, and a world only prose can describe #555
12. test(prose): claims assert consequences, not what was displayed #556
13. feat(prose-tests): record everything the agents do, results included #557
14. fix(discussion-entry): the handoff reports the source it actually had #558
15. fix(prose-tests): the stop hook records, and names the model that walked #559
16. fix(prose-tests): command output was never actually recorded #560
17. feat(prose-tests): judge the walk as told, not the summary returned #561
18. feat(prose-tests): decide in code what an agent should not be deciding #562
19. test(prose): a case starts where a session starts #563
20. feat(prose-tests): walk on Sonnet, judge on Opus, escalate a failure #564
21. test(prose): give the eight read-only cases something that can fail #565
22. test(prose): only walks that can be observed, and checks that survive the trip #566
23. fix(prose-tests): the verdict names only the model the record names #567
24. test(prose): discovery, walked to the point where work first exists #568
25. fix(prose-tests): the asserter judges which of prose or walker was at fault #569
26. docs(conventions): a step whose reference routes every exit still signposts #570
27. test(prose): discovery's epic arm, to the same durability boundary #571
28. fix(prose-tests): keep the walk's closing turn, and name the one live difference #572
29. fix(prose-tests): prescribe the cross-check, drop a check that cannot fire, lint the scope #573
30. test(prose): declare the prose each case actually walks #574
31. fix(investigation): the symptom interview never ran for work shaped in discovery #575
32. feat(prose-tests): conduct — playing a person where a script cannot reach #576
33. fix(prose-tests): what a write put in a file is evidence, not incident #577
34. fix(investigation): the interview starts from the carrier, not over it #578
35. test(prose): quick-fix scoping, the whole definition stage in one walk #579
36. fix(prose-tests): the world log is the walker's record #580
37. fix(prose-tests): a confirmed failure reports both runs' checks #581
38. fix(prose-tests): each prescribed command runs as written #582
39. fix(scoping): context gathering reads the whole carrier, asks only the gaps #583